Local Development Server

1. Introduction

2. Project Structure

3. Core Components

4. Architecture Overview

5. Detailed Component Analysis

6. Dependency Analysis

7. Performance Considerations

8. Troubleshooting Guide

9. Conclusion

10. Appendices

This document explains the local development server implementation and command-line interface functions for the project. It covers:

• Flask development server configuration with debug mode, host binding, and port settings

• CLI functions for local testing and development workflows

• Development environment setup, including dependency installation and server startup procedures

• Examples of local API testing, development workflow integration, and debugging techniques

• The relationship between local development server and production deployment

• Common development issues, environment variable configuration, and performance considerations for local testing

The project includes two local development servers and a set of Python utilities:

• A Flask-based local development server for user management and file upload workflows

• A separate Flask-based Python backend service for contact processing and validation

• Electron main process that launches a React/Vite dev server and integrates with the Python backend

• Python utilities for contact extraction, manual number parsing, and phone number validation

Diagram sources

• electron/src/electron/main.js

• electron/src/electron/utils.js

• electron/package.json

• localhost/app.py

• python-backend/app.py

• python-backend/requirements.txt

• python-backend/extract_contacts.py

• python-backend/parse_manual_numbers.py

• python-backend/validate_number.py

Section sources

• README.md

• electron/src/electron/main.js

• localhost/app.py

• python-backend/app.py

• Local Flask development server (localhost/app.py): Provides HTML forms and JSON APIs for user registration/login, dynamic table creation, and file upload handling. It runs with debug mode enabled.

• Python backend Flask service (python-backend/app.py): Offers health checks, file upload processing, contact extraction from CSV/Excel/TXT, manual number parsing, and phone number validation. It binds to host 0.0.0.0 and port 5034.

• Electron main process (electron/src/electron/main.js): Launches the React/Vite dev server at http://localhost:5173 in development mode and loads the Electron window accordingly.

• Python utilities: Standalone scripts for extracting contacts, parsing manual numbers, and validating phone numbers.

Key configuration highlights:

• Local dev server: debug=True, default host/port unspecified (Flask defaults)

• Python backend: debug=True, host=“0.0.0.0”, port=5034

• Electron dev server: Vite dev server at http://localhost:5173

Section sources

• localhost/app.py

• python-backend/app.py

• electron/src/electron/main.js

• electron/package.json

The local development architecture integrates Electron, a React/Vite dev server, and two Flask services:

• Electron main process detects development mode and loads the React dev server URL

• The local Flask server handles user and file operations for the legacy UI

• The Python backend Flask service exposes REST endpoints for contact processing and validation

• Python utilities can be invoked directly for offline testing

Diagram sources

• electron/src/electron/main.js

• localhost/app.py

• python-backend/app.py

Local Flask Development Server (localhost/app.py)#

• Purpose: Legacy UI and file upload workflows with user management and dynamic table creation

• Flask configuration:

  • Debug mode enabled

  • SQLite database configured

  • CORS enabled for all routes

• Routes:

  • HTML forms for login/signup and file upload

  • JSON APIs for login/signup, table loading, file upload, and table selection

• Data model: User table with JSON field for dynamic tables

• File upload handling: Validates allowed extensions and saves uploads

Diagram sources

• localhost/app.py

Section sources

• localhost/app.py

Python Backend Flask Service (python-backend/app.py)#

• Purpose: REST API for contact processing and validation

• Flask configuration:

  • Debug mode enabled

  • Host bound to 0.0.0.0

  • Port set to 5034

  • Upload folder configured with allowed file types and size limit

• Endpoints:

  • GET /health: Health check

  • POST /upload: Upload and process CSV/Excel/TXT files

  • POST /parse-manual-numbers: Parse manual number entries

  • POST /validate-number: Validate a single phone number

• Utilities:

  • Phone number cleaning and normalization

  • Contact extraction from multiple file formats

  • Error handling and cleanup

Diagram sources

• python-backend/app.py

Section sources

• python-backend/app.py

Electron Development Server Integration#

• Development mode detection via environment variable

• Loads React/Vite dev server at http://localhost:5173

• Enables DevTools in development

• Integrates with both local Flask and Python backend services

Diagram sources

• electron/src/electron/main.js

• electron/src/electron/utils.js

Section sources

• electron/src/electron/main.js

• electron/src/electron/utils.js

• electron/package.json

Python Utilities (CLI Functions)#

• Purpose: Standalone CLI utilities for contact processing and validation

• Functions:

  • Contact extraction from CSV/Excel/TXT

  • Manual number parsing with name/number detection

  • Phone number validation and normalization

• Usage: Run as Python scripts with file arguments or stdin/stdout

Diagram sources

• python-backend/extract_contacts.py

• python-backend/parse_manual_numbers.py

• python-backend/validate_number.py

Section sources

• python-backend/extract_contacts.py

• python-backend/parse_manual_numbers.py

• python-backend/validate_number.py

• Local Flask server depends on:

  • Flask, SQLAlchemy, Flask-CORS, Werkzeug

• Python backend depends on:

  • Flask, Flask-CORS, pandas, openpyxl, xlrd, werkzeug

• Electron dev server depends on:

  • Vite, concurrently, wait-on, electron, react, react-dom

Diagram sources

• localhost/app.py

• python-backend/app.py

• python-backend/requirements.txt

• electron/package.json

Section sources

• localhost/app.py

• python-backend/app.py

• python-backend/requirements.txt

• electron/package.json

• Local Flask server:

  • Uses SQLite in-memory-like persistence; suitable for development

  • File uploads saved to filesystem; ensure adequate disk space

  • Debug mode enabled; avoid enabling in production

• Python backend:

  • Max upload size limited to 16 MB

  • File processing performed synchronously; consider async for heavy loads

  • Phone number cleaning and validation are CPU-bound; batch processing recommended

• Electron dev server:

  • Vite hot reload improves iteration speed

  • Puppeteer headless mode reduces overhead for WhatsApp integration

[No sources needed since this section provides general guidance]

Common development issues and resolutions:

• Local Flask server not starting:

  • Ensure Python dependencies are installed

  • Confirm debug mode is enabled and host/port defaults are acceptable

• Python backend not reachable:

  • Verify host binding to 0.0.0.0 and port 5034

  • Check firewall and network configuration

• Electron dev server failing to load:

  • Confirm Vite dev server is running at http://localhost:5173

  • Ensure NODE_ENV is set to development

• File upload errors:

  • Validate allowed file types and sizes

  • Check upload directory permissions

• Phone number validation failures:

  • Ensure numbers meet length and format requirements

  • Use the validation endpoint to diagnose issues

Section sources

• python-backend/app.py

• python-backend/app.py

• electron/src/electron/main.js

• python-backend/validate_number.py

The local development environment combines an Electron-based UI with two Flask services: a legacy local server for user and file operations, and a Python backend for contact processing and validation. Development workflows leverage Vite for rapid UI iteration, while the Python backend provides robust APIs for data preparation. Proper environment configuration and dependency management are essential for smooth local development and testing.

[No sources needed since this section summarizes without analyzing specific files]

Development Environment Setup#

• Install Electron dependencies:

  • Navigate to electron directory and run npm install

• Install Python backend dependencies:

  • Navigate to python-backend directory and run pip install -r requirements.txt

• Start development server:

  • From electron directory, run npm run dev to launch both React/Vite and Electron

Section sources

• README.md

• README.md

Local API Testing Examples#

• Health check:

  • GET http://localhost:5034/health

• Upload and process contacts:

  • POST http://localhost:5034/upload with multipart/form-data

• Parse manual numbers:

  • POST http://localhost:5034/parse-manual-numbers with JSON payload

• Validate phone number:

  • POST http://localhost:5034/validate-number with JSON payload

Section sources

• python-backend/app.py

Relationship Between Local Development and Production Deployment#

• Local development:

  • Electron dev server loads Vite dev server at http://localhost:5173

  • Local Flask server runs with debug mode enabled

  • Python backend runs with debug mode and binds to 0.0.0.0:5034

• Production deployment:

  • Electron builds static assets and runs packaged app

  • Python backend can be deployed behind a reverse proxy or containerized

  • Local Flask server is intended for development and should not be used in production

Section sources

• electron/src/electron/main.js

• python-backend/app.py

• localhost/app.py

Environment Variable Configuration#

• Electron development:

  • NODE_ENV=development enables dev server loading

• Python backend:

  • No explicit environment variables required; configure host/port in app.run()

Section sources

• electron/src/electron/utils.js

• python-backend/app.py